Handle events via scripts

This topic describes the basic principles of scripting which can be performed to handling the events of a report, and its bands and controls.

Scripting overview

Scripts are program commands, placed within the event handlers of the required report elements. When the specified event occurs (e.g. Before Print), the script code runs.

You can write scripts for a report or any of its elements (bands and controls), to be executed when the report is being previewed, printed or exported.

Although when in the Report Designer, virtually any task can be accomplished without scripting, scripting is made available to extend the standard functionality as far as may be required. And, scripting is the only way to calculate custom summaries (this is detailed in the last section of this topic).

Every report element has a set of script events, which are individual for each element's type. For example, the events of the Detail band are shown in the following image.

Events of the Detail band

After you click on (New) for an event (e.g. the Before Print, which is the most used), the Scripts tab is switched on, where you can manage and edit all the report's scripts.

The Scripts tab

In this tab, for a selected event, a script template is auto-added, in the language specified via the Script Language property of the report.

You can verify that your report's scripts are valid, by clicking on Validate. The validation result is then displayed in the Scripts Errors panel.

Scripts Errors panel

Note that scripts are saved to a file along with the report's layout.

Scripting specifics

  1. Scripting language. The report scripts may be written in one of the following languages that the .NET framework supports - C#, Visual Basic and J#. Since J# is not installed with the framework installation, by default, make sure it is present before writing code in it. The scripting language is specified via the Script Language property of the Report object. It is set to C#, by default.
  2. Scripting scope. Script execution is performed in the following way:

    The report engine generates a temporary class in memory. The names of the variables are defined by the Name properties of the controls and objects they represent. When the script is pre-processed, its namespace directives are cut from the script code and added to the namespace, where the temporary class is defined.

    After pre-processing, all scripts are placed in the code of the temporary class. Then, the resulting class is compiled in memory, and its methods are called when events occur.

    Scripting offers many advantages: you can declare classes (they will become inner classes), variables, methods, etc. A variable declared in one script is accessible in another script, because it is, in fact, a variable of the temporary class.

  3. Reference External Assemblies. The Script References property of the Report object specifies the full paths (including the file names) to the assemblies that are referenced in the scripts used in a report. These paths should be specified for all the assemblies that are included in scripts via the using (C#), Imports (Visual Basic) or import (J#) directives.

    Note: Usually, you don't need include any assembles, because most standard assemblies that you may require in scripts are already referenced by the Report Designer.

Example: Custom summary

In this example, we will display the total number of product unit packs in a group.

To perform this, execute steps similar to the ones described in Add totals to a report, except that for the summary field, you should set the Function property to Custom.

Set the Function property to Custom

Then, the additional events are added to the label's Scripts property.

Events added to the label's Scripts property

You can handle these events in the following way.

Code in C#

Code in Visual Basic

Finally, switch to the Preview tab to view the result.

Sample report